Skip to main content
Provides LiveView routing for Phoenix routers.

​
Overview

The Phoenix.LiveView.Router module provides macros and functions for defining LiveView routes in Phoenix applications. It enables you to mount LiveViews using the live/4 macro and organize related LiveViews into live sessions.

​
Macros

​
live/4

Defines a LiveView route. 
live(path, live_view, action \\ nil, opts \\ [])
​
path
string
required
The URL path for the LiveView route
​
live_view
module
required
The LiveView module to mount
​
action
atom
Optional action name that will be available as @live_action in the LiveView
​
opts
keyword
Options for configuring the route:
  • :container - Tuple for HTML tag and attributes for the LiveView container, e.g., {:li, style: "color: blue;"}
  • :as - Configure the named helper (defaults to :live or LiveView name when using actions)
  • :metadata - Map of metadata for telemetry events and route info
  • :private - Map of private data to put in the plug connection
The HTTP request method that a route defined by live/4 responds to is GET.

​
Examples

Basic LiveView route: 
live "/thermostat", ThermostatLive
LiveView with actions: 
live "/articles", ArticleLive.Index, :index
live "/articles/new", ArticleLive.Index, :new
live "/articles/:id/edit", ArticleLive.Index, :edit
LiveView with container options: 
live "/dashboard", DashboardLive, container: {:main, class: "row"}
Using the action in your template: 
<.live_component :if={@live_action == :new} module={MyAppWeb.ArticleLive.FormComponent} id="form" />

​
live_session/3

Defines a live session for live redirects within a group of live routes. 
live_session(name, opts \\ [], do: block)
​
name
atom
required
Unique name for the live session
​
opts
keyword
Options for configuring the session:
  • :session - Extra session map or MFA tuple to merge with the LiveView session
  • :root_layout - Root layout tuple for initial HTTP render
  • :on_mount - List of hooks to attach to mount lifecycle of each LiveView
  • :layout - Layout the LiveView will be rendered in
​
block
do block
required
Block containing live/4 route definitions
live_session does not work with forward. LiveView expects your live routes to always be directly defined within the main router.
Aliases set with Phoenix.Router.scope/2 are not expanded in live_session arguments. You must use the full module name.

​
Examples

Basic live session: 
live_session :default do
  live "/feed", FeedLive, :index
  live "/status", StatusLive, :index
  live "/status/:id", StatusLive, :show
end
Live session with authentication: 
live_session :admin, on_mount: MyAppWeb.AdminLiveAuth do
  live "/admin", AdminDashboardLive, :index
  live "/admin/posts", AdminPostLive, :index
end
Live session with custom layout: 
live_session :app, root_layout: {MyAppWeb.LayoutView, :app} do
  live "/dashboard", DashboardLive
end

​
Security Considerations

live_session draws boundaries between groups of LiveViews. Key security points:
  • Navigation between sessions: Redirecting between different live_sessions forces a full page reload and establishes a new LiveView connection
  • Authentication: Perform authentication checks in on_mount callbacks, as navigation within a session does not go through the plug pipeline
  • Authorization: Always validate on mount (page access) and handle_event (action permissions)

​
Functions

​
fetch_live_flash/2

Fetches the LiveView flash and merges with controller flash. 
fetch_live_flash(conn, opts \\ [])
​
conn
Plug.Conn.t()
required
The connection struct
​
opts
keyword
Options (currently unused)
​
conn
Plug.Conn.t()
Connection with merged flash
Replaces the default :fetch_flash plug used by Phoenix.Router.

​
Example

defmodule MyAppWeb.Router do
  use Phoenix.Router
  import Phoenix.LiveView.Router

  pipeline :browser do
    plug :fetch_session
    plug :fetch_live_flash
    plug :protect_from_forgery
  end
end